This package contains CyberStarter (a sample ODFCyberdog part written using ODF), and ODFCyberLibrary (generic Cyberdog support code for ODF).
Table of Contents
----------------------
• Summary
• Quick Start
• Theory and Design
• Installation
• Issues
Summary
ODFCyberLibrary is an addition to ODF which makes it easier to support Cyberdog in your part. It is still evolving (since Cyberdog is only beta), and will be updated often on the ODF web site at <http://www.devtools.apple.com/odf/>. You can join the ODF mailing list at <odf-interest@cilabs.org> to discuss this support. There are also Cyberdog-specific mailing lists available from the Cyberdog web site at <http://cyberdog.apple.com/>.
ODFCyberStarter is a minimal Cyberdog/ODF part. It is similar to the CyberPuppy example in that all it does is download text and display it (using TextBox). It implements the recipe for reading text from a CyberStream.
Quick Start
Here is what you need to do to make a Cyberdog part using ODFCyberStarter:
If you haven't installed the ODF Cyberdog support, do so now. This consists of the ODFCyberLibrary (which goes in your ODFDev folder). You also need to make sure that you have placed the Cyberdog headers in your CodeWarrior folder.
• Generate your Part
Use PartMaker to create a part. Open the CyberStarter Template and type in your own part name and company. Generate the part (save it in your ODFDev folder so the relative paths are correct).
• Build It
Open your part's project (CWPPCDebug) in CodeWarrior and choose the Make menu item. The part will be compiled and linked. Your part is now in the CWPPCDebug folder. Make an alias to it and put it in your Editors folder. If you have ODFDev on a different disk than your system folder, then create an Editors folder at the top level of that disk and put the alias in it.
• Configure Cyberdog
ODFCyberStarter displays text, and is bound to the mime type "text/plain". In order to make Cyberdog use your part instead of the CyberTextViewer, open the Editor Setup control panel. Click the "Show All" button, and find the "text/plain" kind. Double-click on that line and choose your part (CyberTextViewer and possibly ODFCyberStarter will also be listed). Then close Editor Setup.
Now any time you try to view a text document (not html), Cyberdog will use your part. If you don't know where any text documents are, you can try this one: <http://www.meer.net/~mlanett/csdemo.txt>.
ODFCyberStarter (and your derivative part) is a text viewer, but since it is just a sample, it's not very good. It doesn't show feedback as it loads the text, and it doesn't scroll. What is illustrated is the minimal work you need to do to implement Cyberdog support in your part. Here are the important places in the source code:
Binding.h:
Notice that in addition to the usual kEditor and kKind, we also have defined kMimeType, in this case "text/plain". If you want to download a different mime type you should change this. You will also need to change kind and category to be appropriate. For example, if you want to display images (such as jpegs), you would choose a kMimeType of "image/jpeg", and category of kODCategoryPainting. Which kind you would choose is unclear, because they aren't necessarily registered (CILabs is in charge of this). In general you should always specify a standard kind; use a propietary one also if you need to, but be sure to always write out data to a kind which other parts can read. In the case of an image you might want to write out a PICT kind.
Part.h and Part.cpp:
CPart inherits from FW_MCyberPart in addition to FW_CPart. In general this seems to be the simplest approach (since you only ever want to have 1 FW_MCyberPart instance, and it needs to communicate with the FW_CPart instance, you might as well make them the same object).
CPart overrides DoSetCyberItem (so it knows when Cyberdog wants it to load a new item), and DoIdle (to implement the loading).
You won't need to change DoSetCyberItem very much. It erases the content of the part (setting the text handle to zero-length) and starts the download.
DoIdle needs to be changed depending on your part's data. The outer portion of the loop stays the same. The inner loop accumulates the text and does an incremental display.
Some other routines were affected. We had to slightly modify the CPart constructor and Initialize method. We also override PrivNewEventDispatcher to assist in dealing with Cyberdog window closing. These changes will be the same for all Cyberdog-aware parts.
Frame.h and Frame.cpp
We've added a DrawUpdate routine. This is just like Draw, except that it doesn't erase the screen first. In fact Draw does an erase and then calls DrawUpdate. We do things like this so that our DoIdle can call DrawUpdate numerous times, each time displaying more and more text. Also, this part is a very lame text viewer and uses TextBox, which erases the screen anyway, causing blinking. Your part should be able to do things more neatly.
Part.r
The binding is the least understood part of OpenDoc, and the hardest to debug, and the area most likely to be screwed up when making a part Cyberdog-savvy. The best reason to begin with ODFCyberStarter is because the binding is set up right. It depends only on the constants in Binding.h, except for the English-language user strings, so you shouldn't have to mess with it for a while.
Theory and Design
ODFCyberLibrary contains these classes:
ODF_FW_OCyberPartExtension (SOM) is a subclass of CyberPartExtension, and overrides all of its public methods. It uses a callback structure (FW_SCyberPartExtensionCallbacks) so that whenever Cyberdog calls it, it can turn around and call you in C++. This class will be moved into the ODFLibrary in the future to reduce the size of your part even further.
FW_MCyberPart (C++) is a C++ class which implements the callbacks used by ODF_FW_OCyberPartExtension. The end result is that any SOM method call from Cyberdog (for example, CyberPartExtension::SetCyberItem) will be turned into a C++ method call. Therefore instead of doing SOM subclassing, you can do C++ subclassing instead. The easiest thing to do is to multiply inherit your C++ part class (CPart) from both FW_CPart (or FW_CEmbeddingPart) and FW_MCyberPart. That way you can implement DoSetCyberItem right in your part class to load your part's data across the network.
Note that the names of the FW_MCyberPart methods are a little different than in CyberPartExtension. Most begin with Do (as in DoSetCyberItem), but two begin with Handle (HandleOpenCyberItem and HandleCyberCommand). The difference is that if you override a "Do" method you should not call inherited, but if you override a "Handle" method then you should call the inherited FW_MCyberPart:: method.
FW_CCyberStream is an "envelope" class for CyberStream. It ensures that the CyberStream is deleted when you are done using it. It even calls Abort if you weren't done reading from it. Here is an example of its use:
With FW_CCyberStream you don't need to worry about exceptions, stream errors, or deleting the stream. It's handled for you.
FW_CCyberBuffer is also an envelope class, this time for a buffer aquired from a CyberStream. Here is what ordinary code would look like (not using this helper class):
Ptr buffer;
Size size;
cs->GetBuffer (ev, &buffer, &size);
FW_TRY {
do_something (ev, buffer, size);
}
FW_CATCH_BEGIN
FW_CATCH_EVERYTHING() {
cs->ReleaseBuffer (ev, buffer);
FW_THROW_SAME();
}
FW_CATCH_END
cs->ReleaseBuffer (ev, buffer);
You can simplify all that code to this:
FW_CCyberBuffer ab (ev, cs);
do_something (ev, ab.GetBuffer(), ab.GetSize());
With FW_CCyberBuffer you don't need to worry about exceptions or releasing the buffer.
ODFCyberStarter is a minimal ODF part provided in PartMaker format, so you can quickly create the shell for a Cyberdog-"Savvy" ODF part. It implements the basic reading recipes above with just a text handle, so you can easily change it depending on your content.
Installation
Before using ODFCyberLibrary you will need to have installed OpenDoc, ODF and CyberDog.
Cyberdog and ODFCyberLibrary are as of this writing still works in progress. You should check the ODF web site and Cyberdog web sites for the latest information. Also, we do not have the Cyberdog SDK on the ODF CD. You will need to download it from the Cyberdog web site.
• Copy ODFCyberLibrary (in the ODF & Cyberdog folder) into your ODFDev folder.
• Optionally copy CyberStarter, or make your own using PartMaker. Again, put it in your ODFDev folder.
• Install the Cyberdog SDK into your CodeWarrior : MacOS Support : Headers folder (the SDK consists of the Public Includes and Cyberdog.stub).
• You will need to add these access paths to your project:
:ODFCyberLibrary:Sources:
:ODFCyberLibrary:CWPPCDebug: (or :CWPPCRelease:)
• You also need to add these files to your project:
Cyberdog.stub (from the Cyberdog SDK)
ODFCyberLibrary.lib (from the :ODFCyberLibrary:CWPPCDebug: folder)
Issues
What if Cyberdog isn't Present?
We haven't yet worked on weak linking against Cyberdog. This will be supported in a later release on the ODF web site.
What if Threads aren't Present?
Cyberdog requires threads, but once weak linking is supported, you will be able to run your part without it, which might mean that threads wouldn't be present either. This will be dealt with along with weak linking.
What about making my part show up in the browser window?
This is on the to-do list. Check the ODF web site (at the top of this document) for the last version of ODFCyberLibrary and CyberStarter.
What about MrC/Symantec/68K?
Other PPC compilers will be supported with netborne releases. 68K will not, since Cyberdog does not run on 68K.
